\section{Configuration}
\label{api-Configuration}

Aspen parses and harmonizes all command-line, configuration file, and
environment settings before it loads your plugins. This information is then
available to your modules via several objects which are dynamically placed in
the global \module{aspen} namespace before your plugins are
loaded---\class{conf}, \class{configuration}, and \class{paths}---and via the
\module{mode} module.


\subsection{\class{conf}}
\label{api-conf}

The \class{aspen.conf} object is an instance of
\class{aspen._configuration.ConfFile}, which subclasses the standard library's
\class{ConfigParser.RawConfigParser} class to represent the
\file{__/etc/aspen.conf} file. In addition to the \class{RawConfigParser} API,
the object supports both attribute and key read-only access; either returns a
dictionary corresponding to a section of the \file{aspen.conf} file. If the
named section does not exist, an empty dictionary is returned.

Your application is free and encouraged to use the \file{aspen.conf} file for
it's own configuration, and to access that information via this object.

To illustrate, here is a minimal \file{aspen.conf} file:

\begin{verbatim}
[my_settings]
foo = bar
\end{verbatim}

Such a file could support code like this:

\begin{verbatim}
import aspen

def wsgi_app(environ, start_response):
    my_setting = aspen.conf.my_settings.get('foo', 'default')
    start_response('200 OK', [])
    return ["My setting is %s" % my_setting]
\end{verbatim}


\begin{seealso}

\seelink{http://docs.python.org/lib/RawConfigParser-objects.html}
{\code{RawConfigParser}}{In addition to the API above, \code{aspen.conf} also
exposes the \code{RawConfigParser} API.}

\end{seealso}


\subsection{\class{configuration}}
\label{api-configuration}

The \code{aspen.configuration} object provides raw access to the parser objects
used to configure your server, and a number of basic settings.

\subsubsection{Parsers}

The various parsers and raw settings are exposed as these members:

\begin{memberdesc}[list]{args}
An argument list as returned by \code{optparse.OptionParser.parse_args}.
\end{memberdesc}

\begin{memberdesc}[ConfFile]{conf}
An instance of \code{aspen._configuration.ConfFile}; see above.
\end{memberdesc}

\begin{memberdesc}[OptionParser]{optparser}
An \code{optparse.OptionParser} instance.
\end{memberdesc}

\begin{memberdesc}[Values]{opts}
An \code{optparse.Values} instance per \code{optparse.OptionParser.parse_args}.
\end{memberdesc}

\begin{memberdesc}[Paths]{paths}
An instance of \code{aspen._configuration.Paths}; see below.
\end{memberdesc}


\subsubsection{Settings}

Furthermore, \code{aspen.configuration} exposes specific configuration settings
as these members:

\begin{memberdesc}[]{address}
A (\var{hostname}, \var{port}) tuple (for \code{AF_INET} and \code{AF_INET6}
address) or string (for \code{AF_UNIX}) giving the address to which Aspen is
bound.
\end{memberdesc}

\begin{memberdesc}[string]{command}
A string giving the command line argument (\var{start}, \var{stop}, etc.).
\end{memberdesc}

\begin{memberdesc}[boolean]{daemon}
A boolean indicating whether Aspen is acting as a daemon.
\end{memberdesc}

\begin{memberdesc}[tuple]{defaults}
A tuple listing the default resource names to look for in a directory.
\end{memberdesc}

\begin{memberdesc}[string]{http_version}
A string indicating the HTTP version to speak, either \code{1.0} or \code{1.1}.
\end{memberdesc}

\begin{memberdesc}[int]{sockfam}
One of \code{socket.AF_INET}, \code{socket.AF_INET6}, and \code{socket.AF_UNIX}.
\end{memberdesc}

\begin{memberdesc}[int]{threads}
A non-zero positive integer; the number of threads in the server's
request-handling thread pool.
\end{memberdesc}


All members are intended to be read-only.


\begin{seealso}

\seelink{http://docs.python.org/lib/module-ConfigParser.html}
{\code{ConfigParser}}{The naming is not PEP 8, but the documentation is fine.}

\seelink{http://docs.python.org/lib/module-optparse.html} {\code{optparse}}{On
the other hand, the documentation for \module{optparse} is rather, um,
convoluted. Good luck!}

\end{seealso}


\subsection{\module{mode}}

\declaremodule{aspen}{mode}
\modulesynopsis{Manage the application life-cycle, from debugging to
production.}

It is often valuable to maintain a distinction between various phases of an
application's lifecycle. The \module{mode} module calls these phases
\dfn{modes}, and identifies four of them, given here in conceptual life-cycle
order:

\begin{tableii}{l|l}{code}{Mode}{Description}
\lineii{debugging}{The application is being actively debugged; exceptions may
    trigger an interactive debugger.}
\lineii{development}{The application is being actively developed; however,
    exceptions should not trigger interactive debugging.}
\lineii{staging}{The application is deployed in a mock-production
    environment.}
\lineii{production}{The application is in live use by its end users.}
\end{tableii}


The expectation is that various aspects of the application---logging, exception
handling, data sourcing---will adapt to the current mode. The mode is set in the
\envvar{PYTHONMODE} environment variable. This module provides API for
interacting with this variable. If \envvar{PYTHONMODE} is unset, it will be set
to \code{development} when this module is imported.

\subsubsection{Members}

The module defines the following functions:

\begin{funcdesc}{get}{}
Return the current \envvar{PYTHONMODE} setting as a lowercase string; will raise
\exception  {EnvironmentError} if the (case-insensitive) setting is not one of
\code{debugging}, \code{development}, \code{staging}, or \code{production}.
\end{funcdesc}

\begin{funcdesc}{set}{mode}
Given a mode, set the PYTHONMODE environment variable and refresh the module's
boolean members. If given a bad mode, \exception{ValueError} is raised.
\end{funcdesc}

\begin{funcdesc}{setAPI}{}
Refresh the module's boolean members. Call this if you ever change
\envvar{PYTHONPATH} directly in the \code{os.environ} mapping.
\end{funcdesc}

The module also defines a number of boolean attributes reflecting the current
mode setting, including abbreviations and combinations. Uppercase versions of
each of the following are also defined (e.g., \code{DEBUGGING}).

\begin{datadesc}{debugging, deb}
\class{True} if \envvar{PYTHONMODE} is set to \code{debugging}.
\end{datadesc}
\begin{datadesc}{development, dev}
\class{True} if \envvar{PYTHONMODE} is set to \code{development}.
\end{datadesc}
\begin{datadesc}{staging, st}
\class{True} if \envvar{PYTHONMODE} is set to \code{staging}.
\end{datadesc}
\begin{datadesc}{production, prod}
\class{True} if \envvar{PYTHONMODE} is set to \code{production}.
\end{datadesc}
\begin{datadesc}{debugging_or_development, debdev, devdeb}
\class{True} if \envvar{PYTHONMODE} is set to \code{debugging} or \code{development}.
\end{datadesc}
\begin{datadesc}{staging_or_production, stprod}
\class{True} if \envvar{PYTHONMODE} is set to \code{staging} or \code{production}.
\end{datadesc}


\subsubsection{Example}

Example usage:

\begin{verbatim}
>>> import mode
>>> mode.set('development')     # can set the mode at runtime
>>> mode.get()                  # and access the current mode
'development'
>>> mode.development            # module defines boolean constants
True
>>> mode.PRODUCTION             # uppercase versions are also defined
False
>>> mode.dev                    # as are abbreviations
True
>>> mode.DEBDEV, mode.stprod    # and combinations
(True, False)
\end{verbatim}


\subsection{\class{paths}}
\label{api-paths}

The \class{aspen.paths} object is an instance of
\class{aspen._configuration.Paths}; it is simply a container for various paths,
all normalized and absolute:

\begin{memberdesc}[string]{root}
the website's filesystem root
\end{memberdesc}

\begin{memberdesc}[string]{__}
the magic directory
\end{memberdesc}

\begin{memberdesc}[string]{lib}
the site's local Python library. First we look for \file{__/lib/python},
then for \file{__/lib/pythonx.y}, using only the first found
\end{memberdesc}

\begin{memberdesc}[string]{pkg}
\file{site-packages} under the site's local Python library,
\file{__/lib/pythonx.y/site-packages}
\end{memberdesc}

\begin{memberdesc}[string]{plat}
the local platform-specific Python library, \file{__/lib/plat-x}
\end{memberdesc}

If there is no magic directory, then \code{__}, \code{lib}, \code{pkg} and
\code{plat} are all \class{None}. If there is, then \code{lib}, \code{pkg} and
\code{plat} are added to \code{sys.path}.
